4: Create Connection

Now that the Issuer has a credential definition, they can start issuing credentials. However, in order to do that, they first need to create a connection to the holder. There are multiple ways to create connections. We will use the /v1/connections/ endpoints in these examples.

Create connection between Holder and Issuer

POST /v1/connections/did-exchange/create-request

This endpoint allows a tenant to send a request to another tenant with a public DID to create a connection. Tenants on the platform are configured to auto-accept connections; therefore, connections will proceed to completion automatically.

The following parameters are available on the endpoint:

• their_public_did The DID of the party you want to connect to.
• alias An alias for the connection. Defaults to None.
• goal Optional self-attested string for sharing the intent of the connection.
• goal_code Similar to goal.
• my_label Will be the wallet label, can be overwritten.
• use_did Your local DID to use for the connection.
• use_did_method The method to use for the connection: "did:peer:2" or "did:peer:4".
• use_public_did Use your public DID for this connection. Defaults to False.

Note: Only one of use_did, use_did_method or use_public_did should be specified. If none of these are specified, a new local DID will be created for this connection.

As the Holder, we create a connection with the Issuer using the did-exchange protocol.

Response:

{
  "alias": "Alice-Faber",
  "connection_id": "165148b3-7e3b-4dec-9568-69694a2ba67f",
  "connection_protocol": "didexchange/1.1",
  "created_at": "2025-01-14T09:31:52.686641Z",
  "error_msg": null,
  "invitation_key": null,
  "invitation_mode": "once",
  "invitation_msg_id": null,
  "my_did": "EYPGsWQrpZbxSEbcHRUZum",
  "state": "request-sent",
  "their_did": "did:sov:VvWbYuE8GAkxCgKp6FnPWK",
  "their_label": null,
  "their_public_did": "did:sov:VvWbYuE8GAkxCgKp6FnPWK",
  "their_role": "inviter",
  "updated_at": "2025-01-14T09:31:52.724460Z"
}

Both tenants can listen to Webhooks to track the progress of the connection being made. Once the state is completed, the connection is established. This can also be verified by fetching connection records for the holder or issuer, and validating that their connection has transitioned to state: completed.

Below is an example of a webhook event indicating the completed state.

Note: The field IDs will be unique to each tenant, i.e., the connection_id of the Issuer will be different from that of the Holder, even though they refer to the same connection.

{
  "wallet_id": "4e0c70fb-f2ad-4f59-81f3-93d8df9b977a",
  "topic": "connections",
  "origin": "multitenant",
  "payload": {
    "alias": "Holder <> Issuer",
    "connection_id": "359b30a2-c98d-4c00-b318-8185d1d0e64d",
    "connection_protocol": "didexchange/1.1",
    "created_at": "2025-01-16T07:57:18.451554Z",
    "error_msg": null,
    "invitation_key": "8Vd5YSVBw5p6BJ8nHngZ2UcCKBmTSxQHoNWfaBQJXW5U",
    "invitation_mode": "once",
    "invitation_msg_id": "0ef82415-20ba-4d1e-818b-92a70355ec6e",
    "my_did": "NXk4JkDpFff4MpnTwvn1Wa",
    "state": "completed",
    "their_did": "LN2WMyrMFH74L1GTkSteka",
    "their_label": "Demo Issuer",
    "their_public_did": null,
    "their_role": "inviter",
    "updated_at": "2025-01-16T07:57:18.748560Z"
  }
}

Next: 5: Issue a Credential